Chip 2007 January, February, March & April

home *** CD-ROM | disk | FTP | other *** search

/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nss / nsspki1.h < prev next >

Wrap

C/C++ Source or Header | 2006-04-20 | 82KB | 2,873 lines

/* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is the Netscape security libraries. * * The Initial Developer of the Original Code is * Netscape Communications Corporation. * Portions created by the Initial Developer are Copyright (C) 1994-2000 * the Initial Developer. All Rights Reserved. * * Contributor(s): * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #ifndef NSSPKI1_H #define NSSPKI1_H #ifdef DEBUG static const char NSSPKI1_CVS_ID[] = "@(#) $RCSfile: nsspki1.h,v $ $Revision: 1.3 $ $Date: 2005/01/20 02:25:49 $"; #endif /* DEBUG */ /* * nsspki1.h * * This file contains the prototypes of the public NSS routines * dealing with the PKIX part-1 definitions. */ #ifndef NSSBASET_H #include "nssbaset.h" #endif /* NSSBASET_H */ #ifndef NSSPKI1T_H #include "nsspki1t.h" #endif /* NSSPKI1T_H */ #ifndef OIDDATA_H #include "oiddata.h" #endif /* OIDDATA_H */ PR_BEGIN_EXTERN_C /* * NSSOID * * The public "methods" regarding this "object" are: * * NSSOID_CreateFromBER -- constructor * NSSOID_CreateFromUTF8 -- constructor * (there is no explicit destructor) * * NSSOID_GetDEREncoding * NSSOID_GetUTF8Encoding */ extern const NSSOID *NSS_OID_UNKNOWN; /* * NSSOID_CreateFromBER * * This routine creates an NSSOID by decoding a BER- or DER-encoded * OID. It may return NSS_OID_UNKNOWN upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_BER * NSS_ERROR_NO_MEMORY * * Return value: * NSS_OID_UNKNOWN upon error * An NSSOID upon success */ NSS_EXTERN NSSOID * NSSOID_CreateFromBER ( NSSBER *berOid ); extern const NSSError NSS_ERROR_INVALID_BER; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSOID_CreateFromUTF8 * * This routine creates an NSSOID by decoding a UTF8 string * representation of an OID in dotted-number format. The string may * optionally begin with an octothorpe. It may return NSS_OID_UNKNOWN * upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_STRING * NSS_ERROR_NO_MEMORY * * Return value: * NSS_OID_UNKNOWN upon error * An NSSOID upon success */ NSS_EXTERN NSSOID * NSSOID_CreateFromUTF8 ( NSSUTF8 *stringOid ); extern const NSSError NSS_ERROR_INVALID_STRING; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSOID_GetDEREncoding * * This routine returns the DER encoding of the specified NSSOID. * If the optional arena argument is non-null, the memory used will * be obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return return null upon error, in * which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NSSOID * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * The DER encoding of this NSSOID */ NSS_EXTERN NSSDER * NSSOID_GetDEREncoding ( const NSSOID *oid, NSSDER *rvOpt, NSSArena *arenaOpt ); extern const NSSError NSS_ERROR_INVALID_NSSOID; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSOID_GetUTF8Encoding * * This routine returns a UTF8 string containing the dotted-number * encoding of the specified NSSOID. If the optional arena argument * is non-null, the memory used will be obtained from that arena; * otherwise, the memory will be obtained from the heap. This routine * may return null upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NSSOID * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 string containing the dotted-digit encoding of * this NSSOID */ NSS_EXTERN NSSUTF8 * NSSOID_GetUTF8Encoding ( const NSSOID *oid, NSSArena *arenaOpt ); extern const NSSError NSS_ERROR_INVALID_NSSOID; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSATAV * * The public "methods" regarding this "object" are: * * NSSATAV_CreateFromBER -- constructor * NSSATAV_CreateFromUTF8 -- constructor * NSSATAV_Create -- constructor * * NSSATAV_Destroy * NSSATAV_GetDEREncoding * NSSATAV_GetUTF8Encoding * NSSATAV_GetType * NSSATAV_GetValue * NSSATAV_Compare * NSSATAV_Duplicate */ /* * NSSATAV_CreateFromBER * * This routine creates an NSSATAV by decoding a BER- or DER-encoded * ATAV. If the optional arena argument is non-null, the memory used * will be obtained from that arena; otherwise, the memory will be * obtained from the heap. This routine may return NULL upon error, * in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_BER * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSATAV upon success */ NSS_EXTERN NSSATAV * NSSATAV_CreateFromBER ( NSSArena *arenaOpt, NSSBER *derATAV ); extern const NSSError NSS_ERROR_INVALID_BER; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSATAV_CreateFromUTF8 * * This routine creates an NSSATAV by decoding a UTF8 string in the * "equals" format, e.g., "c=US." If the optional arena argument is * non-null, the memory used will be obtained from that arena; * otherwise, the memory will be obtained from the heap. This routine * may return NULL upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_UNKNOWN_ATTRIBUTE * NSS_ERROR_INVALID_STRING * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSATAV upon success */ NSS_EXTERN NSSATAV * NSSATAV_CreateFromUTF8 ( NSSArena *arenaOpt, NSSUTF8 *stringATAV ); extern const NSSError NSS_ERROR_UNKNOWN_ATTRIBUTE; extern const NSSError NSS_ERROR_INVALID_STRING; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSATAV_Create * * This routine creates an NSSATAV from the specified NSSOID and the * specified data. If the optional arena argument is non-null, the * memory used will be obtained from that arena; otherwise, the memory * will be obtained from the heap.If the specified data length is zero, * the data is assumed to be terminated by first zero byte; this allows * UTF8 strings to be easily specified. This routine may return NULL * upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_ARENA * NSS_ERROR_INVALID_NSSOID * NSS_ERROR_INVALID_POINTER * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSATAV upon success */ NSS_EXTERN NSSATAV * NSSATAV_Create ( NSSArena *arenaOpt, const NSSOID *oid, const void *data, PRUint32 length ); extern const NSSError NSS_ERROR_INVALID_ARENA; extern const NSSError NSS_ERROR_INVALID_NSSOID; extern const NSSError NSS_ERROR_INVALID_POINTER; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSATAV_Destroy * * This routine will destroy an ATAV object. It should eventually be * called on all ATAVs created without an arena. While it is not * necessary to call it on ATAVs created within an arena, it is not an * error to do so. This routine returns a PRStatus value; if * successful, it will return PR_SUCCESS. If unsuccessful, it will * create an error stack and return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_ATAV * * Return value: * PR_FAILURE upon error * PR_SUCCESS upon success */ NSS_EXTERN PRStatus NSSATAV_Destroy ( NSSATAV *atav ); extern const NSSError NSS_ERROR_INVALID_ATAV; /* * NSSATAV_GetDEREncoding * * This routine will DER-encode an ATAV object. If the optional arena * argument is non-null, the memory used will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return null upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_ATAV * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * The DER encoding of this NSSATAV */ NSS_EXTERN NSSDER * NSSATAV_GetDEREncoding ( NSSATAV *atav, NSSArena *arenaOpt ); extern const NSSError NSS_ERROR_INVALID_ATAV; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSATAV_GetUTF8Encoding * * This routine returns a UTF8 string containing a string * representation of the ATAV in "equals" notation (e.g., "o=Acme"). * If the optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return null upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_ATAV * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 string containing the "equals" encoding of the * ATAV */ NSS_EXTERN NSSUTF8 * NSSATAV_GetUTF8Encoding ( NSSATAV *atav, NSSArena *arenaOpt ); extern const NSSError NSS_ERROR_INVALID_ATAV; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSATAV_GetType * * This routine returns the NSSOID corresponding to the attribute type * in the specified ATAV. This routine may return NSS_OID_UNKNOWN * upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_ATAV * * Return value: * NSS_OID_UNKNOWN upon error * An element of enum NSSOIDenum upon success */ NSS_EXTERN const NSSOID * NSSATAV_GetType ( NSSATAV *atav ); extern const NSSError NSS_ERROR_INVALID_ATAV; /* * NSSATAV_GetValue * * This routine returns an NSSItem containing the attribute value * in the specified ATAV. If the optional arena argument is non-null, * the memory used will be obtained from that arena; otherwise, the * memory will be obtained from the heap. This routine may return * NULL upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_ATAV * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSItem containing the attribute value. */ NSS_EXTERN NSSUTF8 * NSSATAV_GetValue ( NSSATAV *atav, NSSArena *arenaOpt ); extern const NSSError NSS_ERROR_INVALID_ATAV; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSATAV_Compare * * This routine compares two ATAVs for equality. For two ATAVs to be * equal, the attribute types must be the same, and the attribute * values must have equal length and contents. The result of the * comparison will be stored at the location pointed to by the "equalp" * variable, which must point to a valid PRBool. This routine may * return PR_FAILURE upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_ATAV * NSS_ERROR_INVALID_ARGUMENT * * Return value: * PR_FAILURE on error * PR_SUCCESS upon a successful comparison (equal or not) */ NSS_EXTERN PRStatus NSSATAV_Compare ( NSSATAV *atav1, NSSATAV *atav2, PRBool *equalp ); extern const NSSError NSS_ERROR_INVALID_ATAV; extern const NSSError NSS_ERROR_INVALID_ARGUMENT; /* * NSSATAV_Duplicate * * This routine duplicates the specified ATAV. If the optional arena * argument is non-null, the memory required will be obtained from * that arena; otherwise, the memory will be obtained from the heap. * This routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_ATAV * NSS_ERROR_NO_MEMORY * * Return value: * NULL on error * A pointer to a new ATAV */ NSS_EXTERN NSSATAV * NSSATAV_Duplicate ( NSSATAV *atav, NSSArena *arenaOpt ); extern const NSSError NSS_ERROR_INVALID_ATAV; extern const NSSError NSS_ERROR_NO_MEMORY; /* * NSSRDN * * The public "methods" regarding this "object" are: * * NSSRDN_CreateFromBER -- constructor * NSSRDN_CreateFromUTF8 -- constructor * NSSRDN_Create -- constructor * NSSRDN_CreateSimple -- constructor * * NSSRDN_Destroy * NSSRDN_GetDEREncoding * NSSRDN_GetUTF8Encoding * NSSRDN_AddATAV * NSSRDN_GetATAVCount * NSSRDN_GetATAV * NSSRDN_GetSimpleATAV * NSSRDN_Compare * NSSRDN_Duplicate */ /* * NSSRDN_CreateFromBER * * This routine creates an NSSRDN by decoding a BER- or DER-encoded * RDN. If the optional arena argument is non-null, the memory used * will be obtained from that arena; otherwise, the memory will be * obtained from the heap. This routine may return NULL upon error, * in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_BER * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSRDN upon success */ NSS_EXTERN NSSRDN * NSSRDN_CreateFromBER ( NSSArena *arenaOpt, NSSBER *berRDN ); /* * NSSRDN_CreateFromUTF8 * * This routine creates an NSSRDN by decoding an UTF8 string * consisting of either a single ATAV in the "equals" format, e.g., * "uid=smith," or one or more such ATAVs in parentheses, e.g., * "(sn=Smith,ou=Sales)." If the optional arena argument is non-null, * the memory used will be obtained from that arena; otherwise, the * memory will be obtained from the heap. This routine may return * NULL upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_UNKNOWN_ATTRIBUTE * NSS_ERROR_INVALID_STRING * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSRDN upon success */ NSS_EXTERN NSSRDN * NSSRDN_CreateFromUTF8 ( NSSArena *arenaOpt, NSSUTF8 *stringRDN ); /* * NSSRDN_Create * * This routine creates an NSSRDN from one or more NSSATAVs. The * final argument to this routine must be NULL. If the optional arena * argument is non-null, the memory used will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_NO_MEMORY * NSS_ERROR_INVALID_ATAV * * Return value: * NULL upon error * A pointer to an NSSRDN upon success */ NSS_EXTERN NSSRDN * NSSRDN_Create ( NSSArena *arenaOpt, NSSATAV *atav1, ... ); /* * NSSRDN_CreateSimple * * This routine creates a simple NSSRDN from a single NSSATAV. If the * optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_NO_MEMORY * NSS_ERROR_INVALID_ATAV * * Return value: * NULL upon error * A pointer to an NSSRDN upon success */ NSS_EXTERN NSSRDN * NSSRDN_CreateSimple ( NSSArena *arenaOpt, NSSATAV *atav ); /* * NSSRDN_Destroy * * This routine will destroy an RDN object. It should eventually be * called on all RDNs created without an arena. While it is not * necessary to call it on RDNs created within an arena, it is not an * error to do so. This routine returns a PRStatus value; if * successful, it will return PR_SUCCESS. If unsuccessful, it will * create an error stack and return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * * Return value: * PR_FAILURE upon failure * PR_SUCCESS upon success */ NSS_EXTERN PRStatus NSSRDN_Destroy ( NSSRDN *rdn ); /* * NSSRDN_GetDEREncoding * * This routine will DER-encode an RDN object. If the optional arena * argument is non-null, the memory used will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return null upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * The DER encoding of this NSSRDN */ NSS_EXTERN NSSDER * NSSRDN_GetDEREncoding ( NSSRDN *rdn, NSSArena *arenaOpt ); /* * NSSRDN_GetUTF8Encoding * * This routine returns a UTF8 string containing a string * representation of the RDN. A simple (one-ATAV) RDN will be simply * the string representation of that ATAV; a non-simple RDN will be in * parenthesised form. If the optional arena argument is non-null, * the memory used will be obtained from that arena; otherwise, the * memory will be obtained from the heap. This routine may return * null upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 string */ NSS_EXTERN NSSUTF8 * NSSRDN_GetUTF8Encoding ( NSSRDN *rdn, NSSArena *arenaOpt ); /* * NSSRDN_AddATAV * * This routine adds an ATAV to the set of ATAVs in the specified RDN. * Remember that RDNs consist of an unordered set of ATAVs. If the * RDN was created with a non-null arena argument, that same arena * will be used for any additional required memory. If the RDN was * created with a NULL arena argument, any additional memory will * be obtained from the heap. This routine returns a PRStatus value; * it will return PR_SUCCESS upon success, and upon failure it will * create an error stack and return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * NSS_ERROR_INVALID_ATAV * NSS_ERROR_NO_MEMORY * * Return value: * PR_SUCCESS upon success * PR_FAILURE upon failure */ NSS_EXTERN PRStatus NSSRDN_AddATAV ( NSSRDN *rdn, NSSATAV *atav ); /* * NSSRDN_GetATAVCount * * This routine returns the cardinality of the set of ATAVs within * the specified RDN. This routine may return 0 upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * * Return value: * 0 upon error * A positive number upon success */ NSS_EXTERN PRUint32 NSSRDN_GetATAVCount ( NSSRDN *rdn ); /* * NSSRDN_GetATAV * * This routine returns a pointer to an ATAV that is a member of * the set of ATAVs within the specified RDN. While the set of * ATAVs within an RDN is unordered, this routine will return * distinct values for distinct values of 'i' as long as the RDN * is not changed in any way. The RDN may be changed by calling * NSSRDN_AddATAV. The value of the variable 'i' is on the range * [0,c) where c is the cardinality returned from NSSRDN_GetATAVCount. * The caller owns the ATAV the pointer to which is returned. If the * optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * NSS_ERROR_VALUE_OUT_OF_RANGE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSATAV */ NSS_EXTERN NSSATAV * NSSRDN_GetATAV ( NSSRDN *rdn, NSSArena *arenaOpt, PRUint32 i ); /* * NSSRDN_GetSimpleATAV * * Most RDNs are actually very simple, with a single ATAV. This * routine will return the single ATAV from such an RDN. The caller * owns the ATAV the pointer to which is returned. If the optional * arena argument is non-null, the memory used will be obtained from * that arena; otherwise, the memory will be obtained from the heap. * This routine may return NULL upon error, including the case where * the set of ATAVs in the RDN is nonsingular. Upon error, this * routine will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * NSS_ERROR_RDN_NOT_SIMPLE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSATAV */ NSS_EXTERN NSSATAV * NSSRDN_GetSimpleATAV ( NSSRDN *rdn, NSSArena *arenaOpt ); /* * NSSRDN_Compare * * This routine compares two RDNs for equality. For two RDNs to be * equal, they must have the same number of ATAVs, and every ATAV in * one must be equal to an ATAV in the other. (Note that the sets * of ATAVs are unordered.) The result of the comparison will be * stored at the location pointed to by the "equalp" variable, which * must point to a valid PRBool. This routine may return PR_FAILURE * upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * NSS_ERROR_INVALID_ARGUMENT * * Return value: * PR_FAILURE on error * PR_SUCCESS upon a successful comparison (equal or not) */ NSS_EXTERN PRStatus NSSRDN_Compare ( NSSRDN *rdn1, NSSRDN *rdn2, PRBool *equalp ); /* * NSSRDN_Duplicate * * This routine duplicates the specified RDN. If the optional arena * argument is non-null, the memory required will be obtained from * that arena; otherwise, the memory will be obtained from the heap. * This routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDN * NSS_ERROR_NO_MEMORY * * Return value: * NULL on error * A pointer to a new RDN */ NSS_EXTERN NSSRDN * NSSRDN_Duplicate ( NSSRDN *rdn, NSSArena *arenaOpt ); /* * NSSRDNSeq * * The public "methods" regarding this "object" are: * * NSSRDNSeq_CreateFromBER -- constructor * NSSRDNSeq_CreateFromUTF8 -- constructor * NSSRDNSeq_Create -- constructor * * NSSRDNSeq_Destroy * NSSRDNSeq_GetDEREncoding * NSSRDNSeq_GetUTF8Encoding * NSSRDNSeq_AppendRDN * NSSRDNSeq_GetRDNCount * NSSRDNSeq_GetRDN * NSSRDNSeq_Compare * NSSRDNSeq_Duplicate */ /* * NSSRDNSeq_CreateFromBER * * This routine creates an NSSRDNSeq by decoding a BER- or DER-encoded * sequence of RDNs. If the optional arena argument is non-null, * the memory used will be obtained from that arena; otherwise, the * memory will be obtained from the heap. This routine may return * NULL upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_BER * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSRDNSeq upon success */ NSS_EXTERN NSSRDNSeq * NSSRDNSeq_CreateFromBER ( NSSArena *arenaOpt, NSSBER *berRDNSeq ); /* * NSSRDNSeq_CreateFromUTF8 * * This routine creates an NSSRDNSeq by decoding a UTF8 string * consisting of a comma-separated sequence of RDNs, such as * "(sn=Smith,ou=Sales),o=Acme,c=US." If the optional arena argument * is non-null, the memory used will be obtained from that arena; * otherwise, the memory will be obtained from the heap. This routine * may return NULL upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_UNKNOWN_ATTRIBUTE * NSS_ERROR_INVALID_STRING * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSRDNSeq upon success */ NSS_EXTERN NSSRDNSeq * NSSRDNSeq_CreateFromUTF8 ( NSSArena *arenaOpt, NSSUTF8 *stringRDNSeq ); /* * NSSRDNSeq_Create * * This routine creates an NSSRDNSeq from one or more NSSRDNs. The * final argument to this routine must be NULL. If the optional arena * argument is non-null, the memory used will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_NO_MEMORY * NSS_ERROR_INVALID_RDN * * Return value: * NULL upon error * A pointero to an NSSRDNSeq upon success */ NSS_EXTERN NSSRDNSeq * NSSRDNSeq_Create ( NSSArena *arenaOpt, NSSRDN *rdn1, ... ); /* * NSSRDNSeq_Destroy * * This routine will destroy an RDNSeq object. It should eventually * be called on all RDNSeqs created without an arena. While it is not * necessary to call it on RDNSeqs created within an arena, it is not * an error to do so. This routine returns a PRStatus value; if * successful, it will return PR_SUCCESS. If unsuccessful, it will * create an error stack and return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDNSEQ * * Return value: * PR_FAILURE upon error * PR_SUCCESS upon success */ NSS_EXTERN PRStatus NSSRDNSeq_Destroy ( NSSRDNSeq *rdnseq ); /* * NSSRDNSeq_GetDEREncoding * * This routine will DER-encode an RDNSeq object. If the optional * arena argument is non-null, the memory used will be obtained from * that arena; otherwise, the memory will be obtained from the heap. * This routine may return null upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDNSEQ * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * The DER encoding of this NSSRDNSeq */ NSS_EXTERN NSSDER * NSSRDNSeq_GetDEREncoding ( NSSRDNSeq *rdnseq, NSSArena *arenaOpt ); /* * NSSRDNSeq_GetUTF8Encoding * * This routine returns a UTF8 string containing a string * representation of the RDNSeq as a comma-separated sequence of RDNs. * If the optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return null upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDNSEQ * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to the UTF8 string */ NSS_EXTERN NSSUTF8 * NSSRDNSeq_GetUTF8Encoding ( NSSRDNSeq *rdnseq, NSSArena *arenaOpt ); /* * NSSRDNSeq_AppendRDN * * This routine appends an RDN to the end of the existing RDN * sequence. If the RDNSeq was created with a non-null arena * argument, that same arena will be used for any additional required * memory. If the RDNSeq was created with a NULL arena argument, any * additional memory will be obtained from the heap. This routine * returns a PRStatus value; it will return PR_SUCCESS upon success, * and upon failure it will create an error stack and return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDNSEQ * NSS_ERROR_INVALID_RDN * NSS_ERROR_NO_MEMORY * * Return value: * PR_SUCCESS upon success * PR_FAILURE upon failure */ NSS_EXTERN PRStatus NSSRDNSeq_AppendRDN ( NSSRDNSeq *rdnseq, NSSRDN *rdn ); /* * NSSRDNSeq_GetRDNCount * * This routine returns the cardinality of the sequence of RDNs within * the specified RDNSeq. This routine may return 0 upon error, in * which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDNSEQ * * Return value: * 0 upon error * A positive number upon success */ NSS_EXTERN PRUint32 NSSRDNSeq_GetRDNCount ( NSSRDNSeq *rdnseq ); /* * NSSRDNSeq_GetRDN * * This routine returns a pointer to the i'th RDN in the sequence of * RDNs that make up the specified RDNSeq. The sequence begins with * the top-level (e.g., "c=US") RDN. The value of the variable 'i' * is on the range [0,c) where c is the cardinality returned from * NSSRDNSeq_GetRDNCount. The caller owns the RDN the pointer to which * is returned. If the optional arena argument is non-null, the memory * used will be obtained from that areana; otherwise, the memory will * be obtained from the heap. This routine may return NULL upon error, * in which case it will have created an error stack. Note that the * usual string representation of RDN Sequences is from last to first. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDNSEQ * NSS_ERROR_VALUE_OUT_OF_RANGE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSRDN */ NSS_EXTERN NSSRDN * NSSRDNSeq_GetRDN ( NSSRDNSeq *rdnseq, NSSArena *arenaOpt, PRUint32 i ); /* * NSSRDNSeq_Compare * * This routine compares two RDNSeqs for equality. For two RDNSeqs to * be equal, they must have the same number of RDNs, and each RDN in * one sequence must be equal to the corresponding RDN in the other * sequence. The result of the comparison will be stored at the * location pointed to by the "equalp" variable, which must point to a * valid PRBool. This routine may return PR_FAILURE upon error, in * which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDNSEQ * NSS_ERROR_INVALID_ARGUMENT * * Return value: * PR_FAILURE on error * PR_SUCCESS upon a successful comparison (equal or not) */ NSS_EXTERN PRStatus NSSRDNSeq_Compare ( NSSRDNSeq *rdnseq1, NSSRDNSeq *rdnseq2, PRBool *equalp ); /* * NSSRDNSeq_Duplicate * * This routine duplicates the specified RDNSeq. If the optional arena * argument is non-null, the memory required will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_RDNSEQ * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a new RDNSeq */ NSS_EXTERN NSSRDNSeq * NSSRDNSeq_Duplicate ( NSSRDNSeq *rdnseq, NSSArena *arenaOpt ); /* * NSSName * * The public "methods" regarding this "object" are: * * NSSName_CreateFromBER -- constructor * NSSName_CreateFromUTF8 -- constructor * NSSName_Create -- constructor * * NSSName_Destroy * NSSName_GetDEREncoding * NSSName_GetUTF8Encoding * NSSName_GetChoice * NSSName_GetRDNSequence * NSSName_GetSpecifiedChoice * NSSName_Compare * NSSName_Duplicate * * NSSName_GetUID * NSSName_GetEmail * NSSName_GetCommonName * NSSName_GetOrganization * NSSName_GetOrganizationalUnits * NSSName_GetStateOrProvince * NSSName_GetLocality * NSSName_GetCountry * NSSName_GetAttribute */ /* * NSSName_CreateFromBER * * This routine creates an NSSName by decoding a BER- or DER-encoded * (directory) Name. If the optional arena argument is non-null, * the memory used will be obtained from that arena; otherwise, * the memory will be obtained from the heap. This routine may * return NULL upon error, in which case it will have created an error * stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_BER * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSName upon success */ NSS_EXTERN NSSName * NSSName_CreateFromBER ( NSSArena *arenaOpt, NSSBER *berName ); /* * NSSName_CreateFromUTF8 * * This routine creates an NSSName by decoding a UTF8 string * consisting of the string representation of one of the choices of * (directory) names. Currently the only choice is an RDNSeq. If the * optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. The routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_STRING * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSName upon success */ NSS_EXTERN NSSName * NSSName_CreateFromUTF8 ( NSSArena *arenaOpt, NSSUTF8 *stringName ); /* * NSSName_Create * * This routine creates an NSSName with the specified choice of * underlying name types. The value of the choice variable must be * one of the values of the NSSNameChoice enumeration, and the type * of the arg variable must be as specified in the following table: * * Choice Type * ======================== =========== * NSSNameChoiceRdnSequence NSSRDNSeq * * * If the optional arena argument is non-null, the memory used will * be obtained from that arena; otherwise, the memory will be * obtained from the heap. This routine may return NULL upon error, * in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_CHOICE * NSS_ERROR_INVALID_ARGUMENT * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSName upon success */ NSS_EXTERN NSSName * NSSName_Create ( NSSArena *arenaOpt, NSSNameChoice choice, void *arg ); /* * NSSName_Destroy * * This routine will destroy a Name object. It should eventually be * called on all Names created without an arena. While it is not * necessary to call it on Names created within an arena, it is not * an error to do so. This routine returns a PRStatus value; if * successful, it will return PR_SUCCESS. If unsuccessful, it will * create an error stack and return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * * Return value: * PR_FAILURE upon error * PR_SUCCESS upon success */ NSS_EXTERN PRStatus NSSName_Destroy ( NSSName *name ); /* * NSSName_GetDEREncoding * * This routine will DER-encode a name object. If the optional arena * argument is non-null, the memory used will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return null upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * The DER encoding of this NSSName */ NSS_EXTERN NSSDER * NSSName_GetDEREncoding ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetUTF8Encoding * * This routine returns a UTF8 string containing a string * representation of the Name in the format specified by the * underlying name choice. If the optional arena argument is non-null, * the memory used will be obtained from that arena; otherwise, the * memory will be obtained from the heap. This routine may return * NULL upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to the UTF8 string */ NSS_EXTERN NSSUTF8 * NSSName_GetUTF8Encoding ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetChoice * * This routine returns the type of the choice underlying the specified * name. The return value will be a member of the NSSNameChoice * enumeration. This routine may return NSSNameChoiceInvalid upon * error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * * Return value: * NSSNameChoiceInvalid upon error * An other member of the NSSNameChoice enumeration upon success */ NSS_EXTERN NSSNameChoice NSSName_GetChoice ( NSSName *name ); /* * NSSName_GetRDNSequence * * If the choice underlying the specified NSSName is that of an * RDNSequence, this routine will return a pointer to that RDN * sequence. Otherwise, this routine will place an error on the * error stack, and return NULL. If the optional arena argument is * non-null, the memory required will be obtained from that arena; * otherwise, the memory will be obtained from the heap. The * caller owns the returned pointer. This routine may return NULL * upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSRDNSeq */ NSS_EXTERN NSSRDNSeq * NSSName_GetRDNSequence ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetSpecifiedChoice * * If the choice underlying the specified NSSName matches the specified * choice, a caller-owned pointer to that underlying object will be * returned. Otherwise, an error will be placed on the error stack and * NULL will be returned. If the optional arena argument is non-null, * the memory required will be obtained from that arena; otherwise, the * memory will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer, which must be typecast */ NSS_EXTERN void * NSSName_GetSpecifiedChoice ( NSSName *name, NSSNameChoice choice, NSSArena *arenaOpt ); /* * NSSName_Compare * * This routine compares two Names for equality. For two Names to be * equal, they must have the same choice of underlying types, and the * underlying values must be equal. The result of the comparison will * be stored at the location pointed to by the "equalp" variable, which * must point to a valid PRBool. This routine may return PR_FAILURE * upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_INVALID_ARGUMENT * * Return value: * PR_FAILURE on error * PR_SUCCESS upon a successful comparison (equal or not) */ NSS_EXTERN PRStatus NSSName_Compare ( NSSName *name1, NSSName *name2, PRBool *equalp ); /* * NSSName_Duplicate * * This routine duplicates the specified nssname. If the optional * arena argument is non-null, the memory required will be obtained * from that arena; otherwise, the memory will be obtained from the * heap. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a new NSSName */ NSS_EXTERN NSSName * NSSName_Duplicate ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetUID * * This routine will attempt to derive a user identifier from the * specified name, if the choices and content of the name permit. * If the Name consists of a Sequence of Relative Distinguished * Names containing a UID attribute, the UID will be the value of * that attribute. Note that no UID attribute is defined in either * PKIX or PKCS#9; rather, this seems to derive from RFC 1274, which * defines the type as a caseIgnoreString. We'll return a Directory * String. If the optional arena argument is non-null, the memory * used will be obtained from that arena; otherwise, the memory will * be obtained from the heap. This routine may return NULL upon error, * in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_UID * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String. */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSName_GetUID ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetEmail * * This routine will attempt to derive an email address from the * specified name, if the choices and content of the name permit. * If the Name consists of a Sequence of Relative Distinguished * Names containing either a PKIX email address or a PKCS#9 email * address, the result will be the value of that attribute. If the * optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_EMAIL * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5 String */ NSSName_GetEmail ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetCommonName * * This routine will attempt to derive a common name from the * specified name, if the choices and content of the name permit. * If the Name consists of a Sequence of Relative Distinguished Names * containing a PKIX Common Name, the result will be that name. If * the optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_COMMON_NAME * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSName_GetCommonName ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetOrganization * * This routine will attempt to derive an organisation name from the * specified name, if the choices and content of the name permit. * If Name consists of a Sequence of Relative Distinguished names * containing a PKIX Organization, the result will be the value of * that attribute. If the optional arena argument is non-null, the * memory used will be obtained from that arena; otherwise, the memory * will be obtained from the heap. This routine may return NULL upon * error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_ORGANIZATION * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSName_GetOrganization ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetOrganizationalUnits * * This routine will attempt to derive a sequence of organisational * unit names from the specified name, if the choices and content of * the name permit. If the Name consists of a Sequence of Relative * Distinguished Names containing one or more organisational units, * the result will be the values of those attributes. If the optional * arena argument is non-null, the memory used will be obtained from * that arena; otherwise, the memory will be obtained from the heap. * This routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_ORGANIZATIONAL_UNITS * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a null-terminated array of UTF8 Strings */ NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */ NSSName_GetOrganizationalUnits ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetStateOrProvince * * This routine will attempt to derive a state or province name from * the specified name, if the choices and content of the name permit. * If the Name consists of a Sequence of Relative Distinguished Names * containing a state or province, the result will be the value of * that attribute. If the optional arena argument is non-null, the * memory used will be obtained from that arena; otherwise, the memory * will be obtained from the heap. This routine may return NULL upon * error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_STATE_OR_PROVINCE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSName_GetStateOrProvince ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetLocality * * This routine will attempt to derive a locality name from the * specified name, if the choices and content of the name permit. If * the Name consists of a Sequence of Relative Distinguished names * containing a Locality, the result will be the value of that * attribute. If the optional arena argument is non-null, the memory * used will be obtained from that arena; otherwise, the memory will * be obtained from the heap. This routine may return NULL upon error, * in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_LOCALITY * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSName_GetLocality ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetCountry * * This routine will attempt to derive a country name from the * specified name, if the choices and content of the name permit. * If the Name consists of a Sequence of Relative Distinguished * Names containing a Country, the result will be the value of * that attribute.. If the optional arena argument is non-null, * the memory used will be obtained from that arena; otherwise, * the memory will be obtained from the heap. This routine may * return NULL upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_COUNTRY * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */ NSSName_GetCountry ( NSSName *name, NSSArena *arenaOpt ); /* * NSSName_GetAttribute * * If the specified name consists of a Sequence of Relative * Distinguished Names containing an attribute with the specified * type, and the actual value of that attribute may be expressed * with a Directory String, then the value of that attribute will * be returned as a Directory String. If the optional arena argument * is non-null, the memory used will be obtained from that arena; * otherwise, the memory will be obtained from the heap. This routine * may return NULL upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_NAME * NSS_ERROR_NO_ATTRIBUTE * NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSName_GetAttribute ( NSSName *name, NSSOID *attribute, NSSArena *arenaOpt ); /* * NSSGeneralName * * The public "methods" regarding this "object" are: * * NSSGeneralName_CreateFromBER -- constructor * NSSGeneralName_CreateFromUTF8 -- constructor * NSSGeneralName_Create -- constructor * * NSSGeneralName_Destroy * NSSGeneralName_GetDEREncoding * NSSGeneralName_GetUTF8Encoding * NSSGeneralName_GetChoice * NSSGeneralName_GetOtherName * NSSGeneralName_GetRfc822Name * NSSGeneralName_GetDNSName * NSSGeneralName_GetX400Address * NSSGeneralName_GetDirectoryName * NSSGeneralName_GetEdiPartyName * NSSGeneralName_GetUniformResourceIdentifier * NSSGeneralName_GetIPAddress * NSSGeneralName_GetRegisteredID * NSSGeneralName_GetSpecifiedChoice * NSSGeneralName_Compare * NSSGeneralName_Duplicate * * NSSGeneralName_GetUID * NSSGeneralName_GetEmail * NSSGeneralName_GetCommonName * NSSGeneralName_GetOrganization * NSSGeneralName_GetOrganizationalUnits * NSSGeneralName_GetStateOrProvince * NSSGeneralName_GetLocality * NSSGeneralName_GetCountry * NSSGeneralName_GetAttribute */ /* * NSSGeneralName_CreateFromBER * * This routine creates an NSSGeneralName by decoding a BER- or DER- * encoded general name. If the optional arena argument is non-null, * the memory used will be obtained from that arena; otherwise, the * memory will be obtained from the heap. This routine may return * NULL upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_BER * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSGeneralName upon success */ NSS_EXTERN NSSGeneralName * NSSGeneralName_CreateFromBER ( NSSArena *arenaOpt, NSSBER *berGeneralName ); /* * NSSGeneralName_CreateFromUTF8 * * This routine creates an NSSGeneralName by decoding a UTF8 string * consisting of the string representation of one of the choices of * general names. If the optional arena argument is non-null, the * memory used will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The routine may return NULL upon * error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_STRING * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSGeneralName upon success */ NSS_EXTERN NSSGeneralName * NSSGeneralName_CreateFromUTF8 ( NSSArena *arenaOpt, NSSUTF8 *stringGeneralName ); /* * NSSGeneralName_Create * * This routine creates an NSSGeneralName with the specified choice of * underlying name types. The value of the choice variable must be one * of the values of the NSSGeneralNameChoice enumeration, and the type * of the arg variable must be as specified in the following table: * * Choice Type * ============================================ ========= * NSSGeneralNameChoiceOtherName * NSSGeneralNameChoiceRfc822Name * NSSGeneralNameChoiceDNSName * NSSGeneralNameChoiceX400Address * NSSGeneralNameChoiceDirectoryName NSSName * * NSSGeneralNameChoiceEdiPartyName * NSSGeneralNameChoiceUniformResourceIdentifier * NSSGeneralNameChoiceIPAddress * NSSGeneralNameChoiceRegisteredID * * If the optional arena argument is non-null, the memory used will * be obtained from that arena; otherwise, the memory will be * obtained from the heap. This routine may return NULL upon error, * in which case it will have created an error stack. * * The error may be one fo the following values: * NSS_ERROR_INVALID_CHOICE * NSS_ERROR_INVALID_ARGUMENT * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSGeneralName upon success */ NSS_EXTERN NSSGeneralName * NSSGeneralName_Create ( NSSGeneralNameChoice choice, void *arg ); /* * NSSGeneralName_Destroy * * This routine will destroy a General Name object. It should * eventually be called on all General Names created without an arena. * While it is not necessary to call it on General Names created within * an arena, it is not an error to do so. This routine returns a * PRStatus value; if successful, it will return PR_SUCCESS. If * usuccessful, it will create an error stack and return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * * Return value: * PR_FAILURE upon failure * PR_SUCCESS upon success */ NSS_EXTERN PRStatus NSSGeneralName_Destroy ( NSSGeneralName *generalName ); /* * NSSGeneralName_GetDEREncoding * * This routine will DER-encode a name object. If the optional arena * argument is non-null, the memory used will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return null upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * The DER encoding of this NSSGeneralName */ NSS_EXTERN NSSDER * NSSGeneralName_GetDEREncoding ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetUTF8Encoding * * This routine returns a UTF8 string containing a string * representation of the General Name in the format specified by the * underlying name choice. If the optional arena argument is * non-null, the memory used will be obtained from that arena; * otherwise, the memory will be obtained from the heap. This routine * may return NULL upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 string */ NSS_EXTERN NSSUTF8 * NSSGeneralName_GetUTF8Encoding ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetChoice * * This routine returns the type of choice underlying the specified * general name. The return value will be a member of the * NSSGeneralNameChoice enumeration. This routine may return * NSSGeneralNameChoiceInvalid upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * * Return value: * NSSGeneralNameChoiceInvalid upon error * An other member of the NSSGeneralNameChoice enumeration */ NSS_EXTERN NSSGeneralNameChoice NSSGeneralName_GetChoice ( NSSGeneralName *generalName ); /* * NSSGeneralName_GetOtherName * * If the choice underlying the specified NSSGeneralName is that of an * Other Name, this routine will return a pointer to that Other name. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSOtherName */ NSS_EXTERN NSSOtherName * NSSGeneralName_GetOtherName ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetRfc822Name * * If the choice underlying the specified NSSGeneralName is that of an * RFC 822 Name, this routine will return a pointer to that name. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSRFC822Name */ NSS_EXTERN NSSRFC822Name * NSSGeneralName_GetRfc822Name ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetDNSName * * If the choice underlying the specified NSSGeneralName is that of a * DNS Name, this routine will return a pointer to that DNS name. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSDNSName */ NSS_EXTERN NSSDNSName * NSSGeneralName_GetDNSName ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetX400Address * * If the choice underlying the specified NSSGeneralName is that of an * X.400 Address, this routine will return a pointer to that Address. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSX400Address */ NSS_EXTERN NSSX400Address * NSSGeneralName_GetX400Address ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetDirectoryName * * If the choice underlying the specified NSSGeneralName is that of a * (directory) Name, this routine will return a pointer to that name. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSName */ NSS_EXTERN NSSName * NSSGeneralName_GetName ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetEdiPartyName * * If the choice underlying the specified NSSGeneralName is that of an * EDI Party Name, this routine will return a pointer to that name. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSEdiPartyName */ NSS_EXTERN NSSEdiPartyName * NSSGeneralName_GetEdiPartyName ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetUniformResourceIdentifier * * If the choice underlying the specified NSSGeneralName is that of a * URI, this routine will return a pointer to that URI. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSURI */ NSS_EXTERN NSSURI * NSSGeneralName_GetUniformResourceIdentifier ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetIPAddress * * If the choice underlying the specified NSSGeneralName is that of an * IP Address , this routine will return a pointer to that address. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSIPAddress */ NSS_EXTERN NSSIPAddress * NSSGeneralName_GetIPAddress ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetRegisteredID * * If the choice underlying the specified NSSGeneralName is that of a * Registered ID, this routine will return a pointer to that ID. * Otherwise, this routine will place an error on the error stack, and * return NULL. If the optional arena argument is non-null, the memory * required will be obtained from that arena; otherwise, the memory * will be obtained from the heap. The caller owns the returned * pointer. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to an NSSRegisteredID */ NSS_EXTERN NSSRegisteredID * NSSGeneralName_GetRegisteredID ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetSpecifiedChoice * * If the choice underlying the specified NSSGeneralName matches the * specified choice, a caller-owned pointer to that underlying object * will be returned. Otherwise, an error will be placed on the error * stack and NULL will be returned. If the optional arena argument * is non-null, the memory required will be obtained from that arena; * otherwise, the memory will be obtained from the heap. The caller * owns the returned pointer. This routine may return NULL upon * error, in which caes it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_WRONG_CHOICE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer, which must be typecast */ NSS_EXTERN void * NSSGeneralName_GetSpecifiedChoice ( NSSGeneralName *generalName, NSSGeneralNameChoice choice, NSSArena *arenaOpt ); /* * NSSGeneralName_Compare * * This routine compares two General Names for equality. For two * General Names to be equal, they must have the same choice of * underlying types, and the underlying values must be equal. The * result of the comparison will be stored at the location pointed * to by the "equalp" variable, which must point to a valid PRBool. * This routine may return PR_FAILURE upon error, in which case it * will have created an error stack. * * The error may be one of the following value: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_INVALID_ARGUMENT * * Return value: * PR_FAILURE upon error * PR_SUCCESS upon a successful comparison (equal or not) */ NSS_EXTERN PRStatus NSSGeneralName_Compare ( NSSGeneralName *generalName1, NSSGeneralName *generalName2, PRBool *equalp ); /* * NSSGeneralName_Duplicate * * This routine duplicates the specified General Name. If the optional * arena argument is non-null, the memory required will be obtained * from that arena; otherwise, the memory will be obtained from the * heap. This routine may return NULL upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a new NSSGeneralName */ NSS_EXTERN NSSGeneralName * NSSGeneralName_Duplicate ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetUID * * This routine will attempt to derive a user identifier from the * specified general name, if the choices and content of the name * permit. If the General Name is a (directory) Name consisting * of a Sequence of Relative Distinguished Names containing a UID * attribute, the UID will be the value of that attribute. Note * that no UID attribute is defined in either PKIX or PKCS#9; * rather, this seems to derive from RFC 1274, which defines the * type as a caseIgnoreString. We'll return a Directory String. * If the optional arena argument is non-null, the memory used * will be obtained from that arena; otherwise, the memory will be * obtained from the heap. This routine may return NULL upon error, * in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_UID * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String. */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSGeneralName_GetUID ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetEmail * * This routine will attempt to derive an email address from the * specified general name, if the choices and content of the name * permit. If the General Name is a (directory) Name consisting * of a Sequence of Relative Distinguished names containing either * a PKIX email address or a PKCS#9 email address, the result will * be the value of that attribute. If the General Name is an RFC 822 * Name, the result will be the string form of that name. If the * optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_EMAIL * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5String */ NSSGeneralName_GetEmail ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetCommonName * * This routine will attempt to derive a common name from the * specified general name, if the choices and content of the name * permit. If the General Name is a (directory) Name consisting * of a Sequence of Relative Distinguished names containing a PKIX * Common Name, the result will be that name. If the optional arena * argument is non-null, the memory used will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_COMMON_NAME * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSGeneralName_GetCommonName ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetOrganization * * This routine will attempt to derive an organisation name from the * specified general name, if the choices and content of the name * permit. If the General Name is a (directory) Name consisting * of a Sequence of Relative Distinguished names containing an * Organization, the result will be the value of that attribute. * If the optional arena argument is non-null, the memory used will * be obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_ORGANIZATION * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSGeneralName_GetOrganization ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetOrganizationalUnits * * This routine will attempt to derive a sequence of organisational * unit names from the specified general name, if the choices and * content of the name permit. If the General Name is a (directory) * Name consisting of a Sequence of Relative Distinguished names * containing one or more organisational units, the result will * consist of those units. If the optional arena argument is non- * null, the memory used will be obtained from that arena; otherwise, * the memory will be obtained from the heap. This routine may return * NULL upon error, in which case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_ORGANIZATIONAL_UNITS * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a null-terminated array of UTF8 Strings */ NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */ NSSGeneralName_GetOrganizationalUnits ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetStateOrProvince * * This routine will attempt to derive a state or province name from * the specified general name, if the choices and content of the name * permit. If the General Name is a (directory) Name consisting * of a Sequence of Relative Distinguished names containing a state or * province, the result will be the value of that attribute. If the * optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_STATE_OR_PROVINCE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSGeneralName_GetStateOrProvince ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetLocality * * This routine will attempt to derive a locality name from * the specified general name, if the choices and content of the name * permit. If the General Name is a (directory) Name consisting * of a Sequence of Relative Distinguished names containing a Locality, * the result will be the value of that attribute. If the optional * arena argument is non-null, the memory used will be obtained from * that arena; otherwise, the memory will be obtained from the heap. * This routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_LOCALITY * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSGeneralName_GetLocality ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetCountry * * This routine will attempt to derive a country name from the * specified general name, if the choices and content of the name * permit. If the General Name is a (directory) Name consisting of a * Sequence of Relative Distinguished names containing a Country, the * result will be the value of that attribute. If the optional * arena argument is non-null, the memory used will be obtained from * that arena; otherwise, the memory will be obtained from the heap. * This routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_COUNTRY * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */ NSSGeneralName_GetCountry ( NSSGeneralName *generalName, NSSArena *arenaOpt ); /* * NSSGeneralName_GetAttribute * * If the specified general name is a (directory) name consisting * of a Sequence of Relative Distinguished Names containing an * attribute with the specified type, and the actual value of that * attribute may be expressed with a Directory String, then the * value of that attribute will be returned as a Directory String. * If the optional arena argument is non-null, the memory used will * be obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_ATTRIBUTE * NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING * * Return value: * NULL upon error * A pointer to a UTF8 String */ NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */ NSSGeneralName_GetAttribute ( NSSGeneralName *generalName, NSSOID *attribute, NSSArena *arenaOpt ); /* * NSSGeneralNameSeq * * The public "methods" regarding this "object" are: * * NSSGeneralNameSeq_CreateFromBER -- constructor * NSSGeneralNameSeq_Create -- constructor * * NSSGeneralNameSeq_Destroy * NSSGeneralNameSeq_GetDEREncoding * NSSGeneralNameSeq_AppendGeneralName * NSSGeneralNameSeq_GetGeneralNameCount * NSSGeneralNameSeq_GetGeneralName * NSSGeneralNameSeq_Compare * NSSGeneralnameSeq_Duplicate */ /* * NSSGeneralNameSeq_CreateFromBER * * This routine creates a general name sequence by decoding a BER- * or DER-encoded GeneralNames. If the optional arena argument is * non-null, the memory used will be obtained from that arena; * otherwise, the memory will be obtained from the heap. This routine * may return NULL upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_BER * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to an NSSGeneralNameSeq upon success */ NSS_EXTERN NSSGeneralNameSeq * NSSGeneralNameSeq_CreateFromBER ( NSSArena *arenaOpt, NSSBER *berGeneralNameSeq ); /* * NSSGeneralNameSeq_Create * * This routine creates an NSSGeneralNameSeq from one or more General * Names. The final argument to this routine must be NULL. If the * optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_NO_MEMORY * NSS_ERROR_INVALID_GENERAL_NAME * * Return value: * NULL upon error * A pointer to an NSSGeneralNameSeq upon success */ NSS_EXTERN NSSGeneralNameSeq * NSSGeneralNameSeq_Create ( NSSArena *arenaOpt, NSSGeneralName *generalName1, ... ); /* * NSSGeneralNameSeq_Destroy * * This routine will destroy an NSSGeneralNameSeq object. It should * eventually be called on all NSSGeneralNameSeqs created without an * arena. While it is not necessary to call it on NSSGeneralNameSeq's * created within an arena, it is not an error to do so. This routine * returns a PRStatus value; if successful, it will return PR_SUCCESS. * If unsuccessful, it will create an error stack and return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME_SEQ * * Return value: * PR_FAILURE upon error * PR_SUCCESS upon success */ NSS_EXTERN PRStatus NSSGeneralNameSeq_Destroy ( NSSGeneralNameSeq *generalNameSeq ); /* * NSSGeneralNameSeq_GetDEREncoding * * This routine will DER-encode an NSSGeneralNameSeq object. If the * optional arena argument is non-null, the memory used will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return null upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME_SEQ * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * The DER encoding of this NSSGeneralNameSeq */ NSS_EXTERN NSSDER * NSSGeneralNameSeq_GetDEREncoding ( NSSGeneralNameSeq *generalNameSeq, NSSArena *arenaOpt ); /* * NSSGeneralNameSeq_AppendGeneralName * * This routine appends a General Name to the end of the existing * General Name Sequence. If the sequence was created with a non-null * arena argument, that same arena will be used for any additional * required memory. If the sequence was created with a NULL arena * argument, any additional memory will be obtained from the heap. * This routine returns a PRStatus value; it will return PR_SUCCESS * upon success, and upon failure it will create an error stack and * return PR_FAILURE. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME_SEQ * NSS_ERROR_INVALID_GENERAL_NAME * NSS_ERROR_NO_MEMORY * * Return value: * PR_SUCCESS upon success * PR_FAILURE upon failure. */ NSS_EXTERN PRStatus NSSGeneralNameSeq_AppendGeneralName ( NSSGeneralNameSeq *generalNameSeq, NSSGeneralName *generalName ); /* * NSSGeneralNameSeq_GetGeneralNameCount * * This routine returns the cardinality of the specified General name * Sequence. This routine may return 0 upon error, in which case it * will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME_SEQ * * Return value; * 0 upon error * A positive number upon success */ NSS_EXTERN PRUint32 NSSGeneralNameSeq_GetGeneralNameCount ( NSSGeneralNameSeq *generalNameSeq ); /* * NSSGeneralNameSeq_GetGeneralName * * This routine returns a pointer to the i'th General Name in the * specified General Name Sequence. The value of the variable 'i' is * on the range [0,c) where c is the cardinality returned from * NSSGeneralNameSeq_GetGeneralNameCount. The caller owns the General * Name the pointer to which is returned. If the optional arena * argument is non-null, the memory used will be obtained from that * arena; otherwise, the memory will be obtained from the heap. This * routine may return NULL upon error, in which case it will have * created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME_SEQ * NSS_ERROR_VALUE_OUT_OF_RANGE * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A caller-owned pointer to a General Name. */ NSS_EXTERN NSSGeneralName * NSSGeneralNameSeq_GetGeneralName ( NSSGeneralNameSeq *generalNameSeq, NSSArena *arenaOpt, PRUint32 i ); /* * NSSGeneralNameSeq_Compare * * This routine compares two General Name Sequences for equality. For * two General Name Sequences to be equal, they must have the same * cardinality, and each General Name in one sequence must be equal to * the corresponding General Name in the other. The result of the * comparison will be stored at the location pointed to by the "equalp" * variable, which must point to a valid PRBool. This routine may * return PR_FAILURE upon error, in which case it will have created an * error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME_SEQ * NSS_ERROR_INVALID_ARGUMENT * * Return value: * PR_FAILURE upon error * PR_SUCCESS upon a successful comparison (equal or not) */ NSS_EXTERN PRStatus NSSGeneralNameSeq_Compare ( NSSGeneralNameSeq *generalNameSeq1, NSSGeneralNameSeq *generalNameSeq2, PRBool *equalp ); /* * NSSGeneralNameSeq_Duplicate * * This routine duplicates the specified sequence of general names. If * the optional arena argument is non-null, the memory required will be * obtained from that arena; otherwise, the memory will be obtained * from the heap. This routine may return NULL upon error, in which * case it will have created an error stack. * * The error may be one of the following values: * NSS_ERROR_INVALID_GENERAL_NAME_SEQ * NSS_ERROR_NO_MEMORY * * Return value: * NULL upon error * A pointer to a new General Name Sequence. */ NSS_EXTERN NSSGeneralNameSeq * NSSGeneralNameSeq_Duplicate ( NSSGeneralNameSeq *generalNameSeq, NSSArena *arenaOpt ); PR_END_EXTERN_C #endif /* NSSPT1M_H */